fix(logger): add Pino PagerDuty V2 transport support by Reinis-FRP · Pull Request #4914 · UMAprotocol/protocol

Reinis-FRP · 2025-12-19T14:53:53Z

Motivation

The new discord-ticket-api package uses Fastify with Pino logger. The existing PagerDuty V2 transport only supported Winston, so we needed to add Pino support to maintain consistent PagerDuty alerting across all services that use the @uma/logger package.

Summary

Created Pino PagerDuty V2 transport using pino-abstract-transport
Refactored shared configuration and event sending logic into shared/PagerDutyV2Transport.ts to eliminate code duplication between Winston and Pino implementations
Added error serializers (stdSerializers.err) to Pino logger config for proper Error object serialization
Fixed log level conversion to support both Winston string levels and Pino numeric levels
Added comprehensive unit test coverage (44 tests) for shared utilities, Winston transport, and Pino transport

Details

Implementation:

Pino transport (pinoLogger/PagerDutyV2Transport.ts): Stream-based transport running in worker thread, processes newline-delimited JSON logs
Shared utilities (shared/PagerDutyV2Transport.ts): Contains Config type, createConfig validation, convertLevelToSeverity mapping, and sendPagerDutyEvent helper
Winston refactor (logger/PagerDutyV2Transport.ts): Updated to use shared utilities, no functional changes to production behavior

Key technical decisions:

Uses Pino's levels.labels mapping to convert numeric levels (50 = error, 40 = warn, etc.) to string names
Maps unmapped levels (debug, trace) to "info" (lowest PagerDuty severity) instead of "error" to maintain semantic correctness
Both transports filter at level: "error" so only error and fatal logs reach PagerDuty
Added error serializers to properly log Error objects with type, message, and stack trace

Files modified:

packages/logger/src/pinoLogger/PagerDutyV2Transport.ts - New Pino transport
packages/logger/src/pinoLogger/Logger.ts - Added error serializers
packages/logger/src/pinoLogger/Transports.ts - Added PagerDuty config
packages/logger/src/shared/PagerDutyV2Transport.ts - New shared utilities module
packages/logger/src/logger/PagerDutyV2Transport.ts - Refactored to use shared utilities
Test files for all three components

Testing

Ran end-to-end test, running the code as in production (tested with actual PagerDuty integration)
New unit tests created (44 tests covering shared utilities, Winston transport, and Pino transport)
Existing tests adequate, no new tests required
All existing tests pass
Untested

Issue(s)

Part of the work to support Pino logger in new services.

Signed-off-by: Reinis Martinsons <reinis@umaproject.org>

- Create shared PagerDuty config module (types, validation, level conversion) - Implement PagerDutyV2Transport for Pino using pino-abstract-transport - Refactor Winston PagerDutyV2Transport to use shared config - Add createPinoTransports with conditional PagerDuty integration - Fix log level handling (read from env/config instead of hardcoded) - Update createPinoLogger to pass level to transports - Export Transports from logger package index - Match Winston's fail-fast behavior for config validation WIP: needs review and testing before finalizing Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Signed-off-by: Reinis Martinsons <reinis@umaproject.org>

Change from inline type imports (import { type Foo }) to separate import type statements to match project's linter configuration. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Signed-off-by: Reinis Martinsons <reinis@umaproject.org>

Remove re-exports of Config, createConfig, and types from transport files. These were only used internally and are now imported directly from the SharedConfig module by consumers (Transports.ts files). This makes it clear that these are shared utilities, not transport-specific APIs, and prevents them from being inadvertently exposed in the public API. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Signed-off-by: Reinis Martinsons <reinis@umaproject.org>

…sConfig The environment parameter was copied from Winston's interface but is not needed for Pino. Unlike Winston, Pino doesn't require different transports for different environments - it always outputs JSON to stdout which GCP automatically parses. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Signed-off-by: Reinis Martinsons <reinis@umaproject.org>

The previous implementation created a local variable that was never used, so the unmodified mrkdwn was being sent to PagerDuty. Now it directly mutates obj.mrkdwn to match the Winston implementation. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Signed-off-by: Reinis Martinsons <reinis@umaproject.org>

Extract the PagerDuty event() call to a shared sendPagerDutyEvent() helper that accepts the whole log object and routing key. The helper now handles field extraction (level, message, at, botIdentifier) with fallbacks for both Winston and Pino log formats. This eliminates duplication and simplifies both transports - they now just call sendPagerDutyEvent(routing_key, logObj) instead of manually extracting and passing individual fields. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Signed-off-by: Reinis Martinsons <reinis@umaproject.org>

Move the removeAnchorTextFromLinks call into the shared sendPagerDutyEvent helper. This further simplifies both transports and ensures markdown is always cleaned consistently before sending to PagerDuty. Both transports are now extremely simple - just get the routing key and call sendPagerDutyEvent(routing_key, logObj). All field extraction, markdown cleaning, and event formatting is handled by the shared helper. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Signed-off-by: Reinis Martinsons <reinis@umaproject.org>

…nsport.ts Reorganize PagerDuty shared utilities from pagerduty/SharedConfig.ts to shared/PagerDutyV2Transport.ts. This structure: - Matches naming convention of the transport files - Allows shared/ directory to contain other transport utilities - Eliminates the single-file pagerduty/ directory - Clearly indicates these are shared PagerDuty V2 utilities Updated all imports from ../pagerduty/SharedConfig to ../shared/PagerDutyV2Transport. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Signed-off-by: Reinis Martinsons <reinis@umaproject.org>

Remove unnecessary intermediate variables and fallbacks from sendPagerDutyEvent. Directly use logObj fields in payload construction to match original Winston implementation behavior. This preserves the original behavior where missing required fields appear as "undefined" in PagerDuty, making bugs in log formatting obvious. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Signed-off-by: Reinis Martinsons <reinis@umaproject.org>

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Signed-off-by: Reinis Martinsons <reinis@umaproject.org>

- Remove parse: "lines" option which was causing logs to be passed as strings instead of parsed objects - Use Pino's levels.labels to convert numeric levels (50) to strings ("error") in summary - Always log transport errors to console in Pino (no callback mechanism like Winston) This fixes the issue where Pino logs were not being sent to PagerDuty due to incorrect parsing. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Signed-off-by: Reinis Martinsons <reinis@umaproject.org>

Configure Pino with stdSerializers.err to properly serialize Error objects with type, message, and stack properties. This matches Winston's errorStackTracerFormatter behavior and ensures errors are logged correctly instead of appearing as empty objects. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Signed-off-by: Reinis Martinsons <reinis@umaproject.org>

Replace manual numeric range checks with Pino's levels.labels mapping to convert numeric levels to strings. This is cleaner, more maintainable, and reuses Pino's existing infrastructure. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Signed-off-by: Reinis Martinsons <reinis@umaproject.org>

Fix convertLevelToSeverity to map unmapped levels (debug, trace) to "info" (lowest PagerDuty severity) instead of "error" (high severity). This bug was previously hidden because PagerDuty transports filter at level: "error", so debug/trace logs never reached the function in practice. This ensures correct severity mapping if transport level filtering is changed. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Signed-off-by: Reinis Martinsons <reinis@umaproject.org>

Add unit tests for: - Shared utilities (createConfig, convertLevelToSeverity) - Winston PagerDutyV2Transport (routing keys, error handling, callbacks) - Pino PagerDutyV2Transport (stream processing, routing keys, error handling) Tests verify correct behavior for both Winston string levels and Pino numeric levels, custom routing keys via notificationPath, and proper error handling. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Signed-off-by: Reinis Martinsons <reinis@umaproject.org>

Revert discord-ticket-api server.ts changes to master version. These changes will be submitted in a separate PR. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Signed-off-by: Reinis Martinsons <reinis@umaproject.org>

md0x · 2026-01-23T14:24:32Z

packages/logger/src/shared/PagerDutyV2Transport.ts

+// PD v2 severity only supports critical, error, warning or info.
+// Handles both Winston string levels and Pino numeric levels.
+export function convertLevelToSeverity(level?: string | number): Severity {
+  if (!level) return "info";


I notice Winston was returning an error if if (!level), but agree it makes more sense to return info here

md0x · 2026-01-23T14:26:07Z

packages/logger/src/pinoLogger/PagerDutyV2Transport.ts

+        await sendPagerDutyEvent(routing_key, obj);
+      } catch (error) {
+        // Always log transport errors in Pino since there's no callback mechanism like Winston
+        console.error("PagerDuty v2 transport error:", error);


Should we add more context here like:

console.error("PagerDuty v2 transport error:", error, { logObj: obj });

added in c98e474

md0x · 2026-01-23T14:28:03Z

packages/logger/src/pinoLogger/Transports.ts

+    if (transportsConfig.pagerDutyV2Config || process.env.PAGER_DUTY_V2_CONFIG) {
+      // to disable pdv2, pass in a "disabled=true" in configs or env.
+      const { disabled = false, ...pagerDutyV2Config } =
+        transportsConfig.pagerDutyV2Config ?? JSON.parse(process.env.PAGER_DUTY_V2_CONFIG || "null");


if PAGER_DUTY_V2_CONFIG contains an invalid json this will throw an unhandled error. Should we try catch this and so we have a more descriptive error message?

Nit: Eventually adding a test with an invalid config could be nice.

good idea, added error handling in c98e474 and tests in 8b919c5

md0x

LGTM. Just a few comments

- Add log object context to Pino transport error messages for better debugging - Add comprehensive error handling for PAGER_DUTY_V2_CONFIG JSON parsing - Use isRecordStringUnknown from @uma/common to validate parsed config is a proper object - Provide clear error messages for invalid JSON syntax and non-object values Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Signed-off-by: Reinis Martinsons <reinis@umaproject.org>

Add comprehensive tests for createPinoTransports error handling: - Invalid JSON syntax (malformed JSON) - Non-object JSON values (array, null, string, number) - Valid config with disabled flag Addresses PR review feedback requesting test coverage for invalid configs. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Signed-off-by: Reinis Martinsons <reinis@umaproject.org>

md0x

LGTM

Reinis-FRP and others added 18 commits January 20, 2026 15:45

fix(logger): pino pagerduty transport

e7106a3

Signed-off-by: Reinis Martinsons <reinis@umaproject.org>

wip

4a52056

Signed-off-by: Reinis Martinsons <reinis@umaproject.org>

fix(logger): add missing semicolon

a292bff

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Signed-off-by: Reinis Martinsons <reinis@umaproject.org>

Reinis-FRP force-pushed the reinis-frp/pino-pd branch from c0cad53 to 9f838c1 Compare January 20, 2026 15:45

Reinis-FRP changed the title ~~fix(logger): pino pagerduty transport~~ fix(logger): add Pino PagerDuty V2 transport support Jan 20, 2026

Reinis-FRP marked this pull request as ready for review January 20, 2026 16:18

Reinis-FRP requested review from chrismaree, md0x and mrice32 as code owners January 20, 2026 16:18

Reinis-FRP mentioned this pull request Jan 20, 2026

fix(discord-ticket-api): use createPinoLogger with loggerInstance #4921

Merged

5 tasks

md0x reviewed Jan 23, 2026

View reviewed changes

md0x previously approved these changes Jan 23, 2026

View reviewed changes

Reinis-FRP dismissed md0x’s stale review via 8b919c5 January 26, 2026 11:41

Reinis-FRP requested a review from md0x January 26, 2026 11:44

md0x approved these changes Jan 26, 2026

View reviewed changes

Reinis-FRP merged commit 05adb18 into master Jan 26, 2026
18 checks passed

Reinis-FRP deleted the reinis-frp/pino-pd branch January 26, 2026 12:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(logger): add Pino PagerDuty V2 transport support#4914

fix(logger): add Pino PagerDuty V2 transport support#4914
Reinis-FRP merged 20 commits intomasterfrom
reinis-frp/pino-pd

Reinis-FRP commented Dec 19, 2025 •

edited

Loading

Uh oh!

md0x Jan 23, 2026

Uh oh!

md0x Jan 23, 2026

Uh oh!

Reinis-FRP Jan 26, 2026

Uh oh!

md0x Jan 23, 2026

Uh oh!

md0x Jan 23, 2026

Uh oh!

Reinis-FRP Jan 26, 2026

Uh oh!

md0x left a comment

Uh oh!

md0x left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Reinis-FRP commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

md0x Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

md0x Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reinis-FRP Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

md0x Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

md0x Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reinis-FRP Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

md0x left a comment

Choose a reason for hiding this comment

Uh oh!

md0x left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Reinis-FRP commented Dec 19, 2025 •

edited

Loading